Subject: Proposed CPIC pages for mapped conversations

From: "Hildebrand, Jeff" <[email-masked]>
Date: Wed, 16 Feb 94 17:42:00 PST

TO: CIW Data Conversion SIG

Enclosed is a three part document that breifly describes the requirements 
for
mapped conversations, identifies the required CPIC specification changes, 
and
includes the text for the two new calls.  I would like to progress this text 
to AP
before the next CIW.

I would like to get the comments and questions concerning this proposal 
going
asap so as not to miss the window for the next CIW.
Thanks,

Jeff Hildebrand
206 865-4893
[email-masked]/com

 ----------------------- Requirements ------------------------------------
Introduction
The requirement this paper addresses is the encoding and decoding of data 
for
transmission on the a network.  Traditionally the encoding and decoding of
data has been a problem the application's programmer dealt with.  The advent 

of the LU 6.2 protocol saw the first mention that the encoding and decoding 
of
network data stream can be separated from the application program and given
to the underlying system.. LU 6.2 described a user written routine that node 

services could call to perform either encoding or decoding of a network data 

stream.  This method allowed all the programs that processed a specific
transaction type to use a common encode/decode routine.  These routines were 

envisioned to allow not only data conversion but also preprocessing of the
data, for example to rearrange the fields to suit a local record format.
Unfortunately, the concept as specified in the LU 6.2 protocol was not
implemented.  What was implemented is a mechanism which chops an
application's data stream into regular size chunks for transmission and
reconstructs the data record on the receiver's side.  What has become known 
as
mapped conversations in the LU 6.2 environment is really a simple buffering
mechanism.  A simple buffering mechanism is all that is really needed if the 

program only deals in one or two record types and moves those between
homogenous machines.

OSI TP has very different requirements.  The experience I have had writing
OSI programs indicates ASN.1 encoding and decoding of network data
streams can be complex and occupy significant portions of the application
program's code.  This is not an indictment of ASN.1 encoding.  
Architecturally
OSI TP addressed this by removing the encoding and decoding from the
application program and placing it in the U-ASE which is located in the OSI
CRM.  This approach provides three advantages:

1.It allows the applications programmer to focus on the problem to be
solved rather than the mechanical encoding and decoding of data.

2.A small group of one or two people can support an organization in the
construction and maintenance of U-ASEs.  These people can develop
the required skills to create and maintain U-ASEs that only repetitive
usage provides.

3.A single U-ASE can be used by many programs and therefore realizes
all the benefits of code-reuse.

The key is to balance the needs of programs with complex encoding
requirements against those which have very simple needs, the next section
addresses this.

Encoding/Decoding Requirements:
The solution must support the transfer of both application program encoded
network data streams and CRM encoded (ASN.1 or other encoding methods)
network data streams.

The first requirement, application program encoding/decoding, is resolved by 

using the current LU 6.2 mapped conversation mechanism, and the OSI TP
Unstructured Data Transfer U-ASE (UDT).  The application program sends an
internal data structure, for example a COBOL 01 level structure or C 
language
struct, as the network data stream to the receiving program.  This method
works well when the number of programs are small and the computing
platforms are homogeneous, for example they both support OCTAL or EBDIC
character sets.  If the cooperating systems support different character sets 

some form of encoding is required.  Less obvious, is the problem that arise
when too many systems are involved.  Essentially, various systems want
changes in a network data stream to facilitate what they are doing.  These
changes require all other systems to also change.  With a small number of
closely related systems this is not a problem.  As the number of systems
increase this becomes a major problem because systems that have no use for a 

change must implement it, and, worse, simultaneously with all the other
systems.  The coordination required for these changes becomes excessive and
the wasted man hours required to implement the changes for nonbnefitting
system are enormous.  I have a situation at Boeing which illustrates this 
exact
problem, our temporary solution is to put a shim layer that performs a
mapping function between CPIC and the communications stack .  This shim
will go away when CPIC supports external encoding/decoding routines for
mapped conversations.

The second requirement, CRM encoded/decoded network data streams, is
satisfied by supporting the OSI TP CRM's U-ASE, or LU 6.2 Maps (see foot 
note).  This
requires the use of external routines to encode/decode network data streams. 

This method is needed when:

1.The network data stream must be encoded/decode in a manner more
complex than simply sending a program's internal data structure.

2.There is a need to have variations in a network data stream.

How an implementation supports external encode/decode routines is vendor
specific.  The routines could, for example, be in dynamic link libraries or 
link
edited into the load module.

(foot note)  Maps are non-SNA-defined transformation tables or procedures 
that can
be defined by the installation at both the source and target LUs.  Maps can 
specify,
for example, how fields of a mapped-conversation are related to TP
variables (data record) referred to in protocol-boundary verbs. Mapping
is performed by a PS.MC component called the mapper.
SNA Format and Protocol Reference Manual: Architecture Logic for LU Type 
6.2,
SC30-3269,  page 2-39

 -----------------------------  Change pages -------------------------

Page 10: replace mapped conversation paragraph with
*Mapped conversations allow programs to exchange arbitrary data records
in data formats agreed upon by the application programmers.  If no
map_name is set, via a SET_MAP_NAME call, the data record is treated
as it was in CPIC 1.0.  If a map_name is supplied the sender and receiver
will use external routines to encode/decode the data record as well as
perform any other agreeded upon processing.  How these routines are
written, stored, and attached to user programs is implementation specific,
and not specified by this specification.

Page 17: add to starter set calls SET_MAP_NAME and EXTRACT
_MAP_NAME.  These should be added here instead of under advanced
functions because the default conversation type is mapped.

Page 23: add to Characteristics and their default values table - map_name.  
For
all four cases indicate "Not set".

Page 33: add to last paragraph of Data Conversion after last sentence.  
Refer
mapped conversation calls SET_MAP_NAME on page xyz and
EXTRACT_MAP_NAME on page xyz for more advanced data
conversion capabilities.

Page 87: add to call reference table.
    Set_Map_Name  CMSTMP  Used by an application program to tell CPI-C
            what encoding routine to use.
    Extract_Map_Name  CMEXMP Used by the local system to inform the
           application program what data record it received.

Page 110: add to related information.  "Extract_Map_Name (CMEXMP) on
page xx provides information on data conversion using mapped
conversations.

Page 112: add to related information.  "Set_Map_Name (CMSTMP) on page
xx provides information on data conversion using mapped conversations.

Page 184: add to related information.  "Extract_Map_Name (CMEXMP) on
page xx provides information on data conversion using mapped
conversations.

Page 184: add to Usage Notes.
4. If a mapped conversation is using the map_name characteristic, on a 
receive
delallocate the program will perform two receives.  The first receive will
return CM_OK and CM_DATA_COMPLETE, the program can then issue
an Extract_Map_Name to learn what data record was sent.  The second
receive will return a CM_OK DELLAOCATE, there will be no user data
return and the program can terminate.

Page 198: add to related information.  "Set_Map_Name (CMSTMP) on page
xx provides information on data conversion using mapped conversations.

Page 198: add to Usage Notes.
10. The map_name characteristic is persistant and only needs to be set when
the map_name being used differs from the previous name.  For example, a
program which uses only one map_name need only set it once.

Page 336: State tables.  Add to Receive(I) & (W) event {ok} {dr no} a note.
Note: In the case of mapped conversation receiving a Receive_and_Deallocate
will behave in one of two ways.  Mapped conversations which do not use
the map_name characteristic the receiver will receive the data record and a
DEALLOCATE indication.  Mapped conversations which use the
map_name characteristics will execute two receives.  The first will receive
the decoded data record and the CM_OK DATA_COMPLETE
indications.  The second receive will receive a DEALLOCATE indication,
and no user data will be returned.  This sequence allows the program to
issue an Extract_Map_Name call after the first receive.

Proposed new calls, as presented in the December 
meeting.-----------------------
 -

Set_Map_Name (CMSTMP)

Set_Map_Name (CMSTMP)
A program uses the Set_Map_Name (CMSTMP) call to communicate to the local 
system
what data record the application program is going to send.  The remote 
partner program
uses the Extract_Map_Name to retrieve the name of the data record it was 
sent.  This
service must be used if the program sends multiple data record types.  It 
may be ignored if
the mapped conversation only supports one data record type.
Depending on the underlying CRM the data record may be further processed 
when it is
given to the local system at SEND_DATA time, see usage notes.

Format

CALL CMSTMP    (conversation_ID,
               map_name,
               return_code)
Parameters

Conversation_ID (input)
Specifies the variable containing the conversation identifier
assigned to the conversation.

map_name (input)
Specifies the mapping function to be used to encode the
data record.  This is a positive integer value.

return_code (output)
Specifies the result of call execution.  The return_code
variable can have one of the following values:

*    CM_OK
*    CM_PROGRAM_STATE_CHECK
     This value indicates that the sym_dest_name specifies
          an unrecognized value.
*    CM_OPERATION_NOT_ACCEPTED
          This value indicates the map_name value was not valid
          map.
*    CM_PRODUCT_SPECIFIC_ERROR

State Changes
This call does not cause a state change.  If more than one data record type 
is supported
this service must be invoked prior to a SEND_DATA.

Usage Notes
Programs which only have one map name, e.g., have only one data record type 
can ignore
this service.  The MAP_NAME for a mapped conversation has a default value of 
1.

Related Information
LU 6.2 CRM's use this service to set the MAP_NAME parameter on the
MC_SEND_DATA service to "YES (value of the Set_Map MAP_NAME parameter)".

OSI TP CRM's passes the service's MAP_NAME parameter to the U-ASE which:

     1.Encodes the data record using the proper abstract syntax. Note, there 
is no need to
          transmit the map_name because it is carried as the tag for the 
specific ASN.1
          construct used to encode the data.
     2.Performs any other user defined action on the data record.  An 
example of this
          would be a security transformation on the data record.

Extract_Map_Name (CMEXMP)

Extract_Map_Name (CMEXMP)

A program uses the Extract_Map_Name (CMEXMP) call to communicate to the 
local
system what data record is to be sent.  The receiving program uses the
Extract_Map_Name to retrieve the name of the data record it was sent.
Depending on the underlying CRM the data record may be further processed 
when it is
given to the local system at SEND_DATA time, see usage notes.

Format
CALL CMSTMP    (conversation_ID,
               map_name,
               return_code)

Parameters

Conversation_ID (input)
Specifies the variable containing the conversation identifier
assigned to the conversation.

map_name (output)
Specifies the mapping function used to encode the data
record.  This is a positive integer value.

return_code (output)

Specifies the result of call execution.  The return_code
variable can have one of the following values:
*    CM_OK
*    CM_PROGRAM_STATE_CHECK
     This value indicates that the sym_dest_name specifies
          an unrecognized value.
*    CM_OPERATION_NOT_ACCEPTED
     This value indicates the map_name value was not valid
          map.
*    CM_PRODUCT_SPECIFIC_ERROR

State Changes

This call does not cause a state change.  If more than one data record type 
is supported
this service must be invoked after a RECEIVE.

Usage Notes
Programs which only have one map name, e.g., have only one data record type 
can ignore
this service.  The MAP_NAME for a mapped conversation has a default value of 
1.

Related Information
LU 6.2 CRM MC_RECEIVE_XXX services will have the MAP_NAME parameter set to
the incoming map_name.

OSI TP CRM U-ASEs will know what the map name is from the ASN.1 tag of the
incoming user data record.  The Extract_Map_Name service is used to find out 
what data
record was sent so that it can be properly processed.